Setting FirstClass Web Services as oAuth2 Ticket-Granting-Authority Server
----------------------------------------------------------------------------
1. Creating a trusted-superuser account on FirstClass Server

A trusted-superuser is an account with special privileges that allow it act on behalf of 
other users requesting access tokens. It obtains and returns an access token to the requesting
user. To do so:

1) Create a user on FirstClass Server. For example, with userid "oauth2_requester" and password "oauth2_pass".
2) Logged in to FirstClass Server with administrative privileges, use batch admin command to activate the user:

ACTIVATE USER oauth2_requester TRUSTED

2. Configuring FirstClass Web Server to use oAuth2 trusted-superuser

Using FirstClass Web Server Configuration Tool, log in with administrative privileges.
Once logged in, from the menu select "Generate SHA512 Digest" and type in the userid and password
of the trusted-superuser created in the previous step. Click on button "Digest". The response
tab will contain the corresponding SHA512 digest for the given userid and password.

In any text editor open FirstClass Web Services configuration file and enter fields:

oAuth2User=<userid of the trusted-superuser>
oAuth2Hash=<cut-and-paste the generated SHA512 value from the FCWS Configuration Tool>

Trusted-superusers permissions are coupled with "know addresses". In other words trusted-superusers
will be granted access to FirstClass Server only if the request originated from registered, well
know address. For oAuth2 requests we register the local FCWS Server address. This address must
be specified in the FCWS configuration file with the parameter:  

MyIP=<IP address of this FirstClass Web Server>

In turn, this IP address is then registered in the FirstClass Server FCS.INI file as parameter:

[FCSetup]
TrustedIPs=<semicolon delimited list of trusted IP addresses>









Registering and Authenticating Web Server Applications on FirstClass oAuth2 Ticket-Granting-Authority Server
------------------------------------------------------------------------------------------------------------ 
1. Preparing

Before any authentication can begin, an external web application has to be registered
on the FirstClass oAuth2 Server using the Web Server Registration Tool.
To activate Web Server Registration Tool use url:

http://<FC Web Server URL>/oauth2setup

Based on the redirection uri FirstClass Web Server will register the redirect_uri and
generate and return web application credentials needed for authentication.
For example, external web application redirect uri an be:

https://example.app.com/oauth

Based on this, generated credentials would be:

authorization_uri:		https://fcws.firstclass.com/oauth2/authorize
resource_uri:			https://fcws.firstclass.com/oauth2/token
ticket_granting_uri:	https://fcws.firstclass.com/oauth2/ticket
client_id:				kjdshfh57ty8ghodig485godfi
client_secret:			fdlkgjwo85up49684hgpwiuth2

Where authorization_uri determines where the initial authorization request is send,
ticket_granting_uri is where to send a request for and obtain an access_token and
resource_uri is where to submit the access_token to gain access to the resource.
Credentials client_id and client_secret must be submitted when requesting an access_token.

2. Authorization

 Authorization request is a https GET request for authorization code sent to the authorization_uri
 along with the resource_uri, client_is and resoponse_type=code as url query parameters. For example:
 
 https://fcws.firstclass.com/oauth2/authorize?response_type=code&resource_uri=https%3A%2F%2Ffcws%2Ffirstclass%2Fcom&client_id=kjdshfh57ty8ghodig485godfi
 
 Optionally, a query parameter stat=<arbitrary data> can be sent also and it will be echoed in the reply.
 
 Once resource_uri and client_id are verified the client is prompted with the FirstClass login screen.
 Upon successful login into a FirstClass account, the client is again prompted for access permissions.
 Access permissions prompt has 3 options:
 (1) Cancel - access to account is not granted - abort authentication 
 (2) Once - access token is granted only for one time and no refresh token is issued
 (3) Allow - full access is granted with access token and refresh token
 
 Selecting (2) or (3) FirstClass Server redirects the client to its redirect_uri for 
 code-token exchange. When (2) is selected the client will be given access to FirstClass
 account but will not be given a refresh token for subsequent login. 
 Selecting (3), is same as (2) but the client receives a refresh token for subsequent login.
 
 3. Redirect
 
 Client is redirected to its redirect_uri with the code attached.
 
 HTTP/1.1 302 Found
 Location: https://example.app.com/oauth?code=JHBYCTRCYUYB876GYTY&state=xyz
 
 The external web server can now issue a request for access token:
 
POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

code=JHBYCTRCYUYB876GYTY&
client_id=kjdshfh57ty8ghodig485godfi&
client_secret=fdlkgjwo85up49684hgpwiuth2&
redirect_uri=https%3A%2F%2Fexample%2Fapp%2Fcom/oauth&
grant_type=authorization_code

A successful response is JSON:

{
  "access_token":"fFAGRNJru1FTz70BzhT3Zg",
  "expires_in":120,
  "token_type":"Bearer"
  "refresh_token":"KHKUYguyfgdwouy56854gg"
}

4. Submitting the access token

Gaining access to the FirstClass account with the access token can be done in 2 ways:

(1) Submitting the token in an HTTP GET as a query parameter:

 GET https://fcws.firstclass.com?access_token=fFAGRNJru1FTz70BzhT3Zg
 
 or
 
 (2) Submitting the token in an HTTP GET as header parameter Authorization:
 
 GET https://fcws.firstclass.com/oauth2/token
 Authorization: Bearer 1/fFAGRNJru1FTz70BzhT3Zg
 
 4. Obtaining a new access token with the refresh token
 
 To obtain a new access token, external web server application must issue HTTP POST:
 
POST /oauth2/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=KHKUYguyfgdwouy56854gg
client_id=kjdshfh57ty8ghodig485godfi&
client_secret=fdlkgjwo85up49684hgpwiuth2&
redirect_uri=https%3A%2F%2Fexample%2Fapp%2Fcom/oauth

Response is JSON:
HTTP/1.1 200 OK
{
  "access_token":"JHJHJHJNJru1FTz70BzhT3Zg",
  "expires_in":120,
  "token_type":"Bearer",
}

Note that the request for access token with refresh token requires all client credentials to
be submitted along with the refresh token.

